VSCode 扩展设计实践：一个结构化日志查看器

机器人控制器落盘的日志是结构化的：时间戳、来源、分类、级别各占一段，正文里还常带 JSON 块。拿编辑器打开只有纯文本的灰白一片，想按级别过滤、按时间圈定范围、在命中行之间跳转，都得靠肉眼。本文记录一个 VSCode 扩展的设计：打开 .log 文件自动解析着色，提供五维过滤（级别、来源、分类、时间范围）、双目标搜索、书签、统计与导出。它由一个已有的 Python 终端版工具移植而来，本文聚焦移植中定下的五个设计决策与两个踩过的坑，不罗列功能清单。

三层架构：core 层零 vscode 依赖

扩展分三层，依赖单向：ui → editor → core。

• core 层是纯逻辑：日志解析器、条目库与倒排索引、着色分类、装饰裁剪，五个文件零 vscode import；
• editor 层做宿主接线：每文档状态管理、事件订阅、装饰应用；
• ui 层收集用户意图：命令面板、常驻侧栏面板。

这样切分的直接收益是可测试性：全部单元测试不启动扩展宿主，mocha 在裸 Node 直载编译产物即可断言——不用 @vscode/test-electron，不下载 Electron，测试秒级完成。代价是宿主 API 的调用被集中到 editor 层少数文件里，core 想引用 vscode 的任何东西都会在构建时报错，这道墙反过来保证了分层不腐化。

另一个原则是一切运行态可重建：条目主数组是唯一事实源，三张倒排索引、过滤下标表、过滤视图文本、搜索行偏移全部是它的派生物。没有持久化状态，重新解析即全量重建，parseSource 这类行为开关做成会话级，避开了状态落盘与迁移的一整类问题。

过滤视图：虚拟文档与无缝子集

过滤最容易想到的实现是「把命中行拼成一个新文本」。但过滤结果需要被浏览、被搜索、被定位行号，自己拼文本就要自己重造这些轮子。

这里的选择是把过滤结果做成虚拟文档：注册一个自定义 scheme（形如 logview://filtered/）的 TextDocumentContentProvider，内容回调返回命中条目的文本。VSCode 把它当普通只读文档打开，原生的大文件渲染、文档内搜索、只读语义全部免费获得。过滤条件变化时，provider 的 onDidChange 事件以同一个 URI fire 一次，宿主就会重新调用内容回调刷新已打开的视图——这套事件机制是官方虚拟文档指南的标准用法。

内容生成遵守一条「无缝子集」契约：只输出命中条目的原文和它们的 JSON 续行，不加行号前缀、不做缩进，列偏移与原文件一致。这不是洁癖：着色逻辑是按列区间切颜色段的，列偏移一致意味着源文档的着色切片可以零改动复用到过滤视图；原文逐字节保留则保证「从过滤结果导出」能无损回环到原始日志格式。

装饰视口分批：滚动成本与文件大小解耦

语法着色用装饰（decoration）API 实现：把每行切成带列区间的颜色段，按装饰类型分组后批量 setDecorations。问题在于大文件——百万行的颜色段一次性应用，扩展进程直接卡死。

解法是视口分批：任何时刻只对「可见行 + 200 行缓冲」计算并应用装饰，滚动、编辑器切换、解析完成各触发一次批量刷新。裁剪后实际应用的段通常只剩千分之几，滚动一次的开销全部花在可见行上。实测数据（自建基准，供量级参考）：

文件规模	解析 + 建索引	每次滚动装饰
10 万行（约 8MB）	约 140ms	约 5ms
100 万行（约 83MB）	约 1.4s	约 25ms

滚动开销与文件大小无关，这是装饰方案能撑住大文件的前提；真正的性能上界变成了解析——同步全文解析在 GB 级文件上要十几秒，只能靠 worker 线程卸载（预留优化，当前未做）。

行为基准：ground truth 回归

从 Python 移植到 TypeScript，「行为一致」不能靠感觉。做法是把 Python 版对一份 266 条目的真实日志的解析结果逐字段导出成 JSON（时间戳、级别、分类原文、续行归属……），作为 ground truth 入库；TS 版解析器的单元测试对着它逐字段比对。

仲裁规则写死在流程里：两个版本行为分叉时，以 ground truth 为准修 TS 版；除非分叉是有意的修复——此时更新样例与用例，并在 CHANGELOG 里记录动机。项目全程只有一处有意分歧（source 字段的字符集从纯小写放宽到含数字与大写），这条规则让「移植偏差」和「计划内改进」始终可区分。

两个跨视图状态缺陷

源文档和过滤视图是两个行号空间：源文档行号是原文件的 1-based 行号，过滤视图是重排后的 0-based 稠密行号。两处真实缺陷都栽在这个跨空间上。

缺陷一：搜索静默丢结果。 过滤视图出现后，源文档的搜索被顺手改成只扫「过滤后可见」的条目——用户在源文档里搜一个确实存在、但被过滤掉的字符串，得到零结果且没有任何提示。修复是给搜索接口加 scope 参数：源文档目标显式传「全量」，过滤视图目标才传「可见」。教训是结果集和作用域要跟着调用方走，共享一个「当前可见集合」的隐式状态迟早出错。

缺陷二：高亮串视图。 搜索高亮状态最初只有一份行号数组，源视图搜索后被过滤、再打开过滤视图——高亮行号按另一套行号空间解释，未命中的行也被点亮。修复是给高亮状态加 target 字段（source / filtered），四处入口做归属检查：非本视图的高亮不绘制、不导航，过滤变化使旧高亮失效。教训同源：跨视图共享状态必须携带归属，谁的状态谁消费。

两个修复各自补了回归用例，此后再没复发。这类缺陷的共性是单看每个模块都「正确」，出错的是模块之间共享的隐式约定——回归用例锁住约定，比锁住代码更重要。

异常处理：降级不抛

面向日志文件的扩展要预设输入千奇百怪。核心容错模式是「非法输入降级为空结果 + 用户可见反馈，不抛异常打断」：

• 非法正则：搜索返回空结果，游标复位，后续「下一个」是无害空操作；
• 过滤视图的源文档未打开：虚拟文档内嵌一行提示文字，不弹窗；
• 面板时间输入不可解析：警告并取消整次过滤，避免半个条件生效；
• 解析失败：状态栏与错误消息可见报错，扩展继续工作。

后台路径（面板重新可见时补偿触发的自动解析）则一律静默吞错——它没有用户等待，报错只会制造噪音。显式动作有声反馈、后台任务静默保活，这条线划清后异常出口就收敛了。

结语

• 三层架构 + core 零宿主依赖，换来测试脱离扩展宿主、秒级运行；
• 过滤结果做成虚拟文档，无缝子集契约（原文逐字节、列偏移一致）让渲染、搜索、着色、导出全部复用宿主与源文档的能力；
• 装饰只作用于视口加缓冲，滚动开销与文件大小解耦，性能上界转移到解析；
• 移植行为用 ground truth 逐字段锁定，有意分歧走 CHANGELOG；
• 跨视图共享状态带归属、作用域跟调用方走——两处真实缺陷都出在这里，也都被回归用例锁死。